import { Callout } from 'nextra/components';
import { NextSeo } from 'next-seo';
import { Tab, Tabs } from 'nextra/components';

<NextSeo description="Run Laravel serverless on AWS Lambda using Bref." />

# Serverless Laravel - Getting started

This guide helps you run Laravel applications on AWS Lambda using Bref. These instructions are kept up to date to target the latest Laravel version.

<Callout>
    A demo application is available on GitHub at [github.com/brefphp/examples](https://github.com/brefphp/examples).
</Callout>

## Setup

First, **follow the [Setup guide](../setup.mdx)** to create an AWS account and install the necessary tools.

Next, in an existing Laravel project, install Bref and the [Laravel-Bref package](https://github.com/brefphp/laravel-bridge).

```bash
composer require bref/bref bref/laravel-bridge --update-with-dependencies
```

Then let's create a [`serverless.yml` configuration file](../environment/serverless-yml.mdx):

```bash
php artisan vendor:publish --tag=serverless-config
```

### How it works

By default, the Laravel-Bref package will automatically configure Laravel to work on AWS Lambda.

If you are curious, the package will automatically:

- enable the `stderr` log driver, to send logs to CloudWatch ([read more about logs](../environment/logs.md))
- enable the [`cookie` session driver](https://laravel.com/docs/session#configuration) (if you prefer, you can configure sessions to be stored in database, DynamoDB or Redis)
- move the storage directory to `/tmp` (because the default storage directory is read-only on Lambda)
- adjust a few more settings ([have a look at the `BrefServiceProvider` for details](https://github.com/brefphp/laravel-bridge/blob/master/src/BrefServiceProvider.php))

## Deployment

We do not want to deploy "dev" caches that were generated on our machine (because paths will be different on AWS Lambda). Let's clear them before deploying:

```bash
php artisan config:clear
```

When running in AWS Lambda, the Laravel application will automatically cache its configuration when booting. You don't need to run `php artisan config:cache` before deploying.

Let's deploy now:

<Tabs items={['Serverless CLI', 'Bref Cloud']}>
    <Tab>
        ```bash
        serverless deploy
        ```
    </Tab>
    <Tab>
        ```bash
        bref deploy
        ```
    </Tab>
</Tabs>

When finished, the `deploy` command will show the URL of the application.

### Deploying for production

At the moment, we deployed our local codebase to Lambda. When deploying for production, we don't want to deploy:

- development dependencies,
- our local `.env` file,
- or any other dev artifact.

Follow [the deployment guide](/docs/deploy.md#deploying-for-production) for more details about deploying in general.

Specifically for Laravel, Bref will automatically cache the configuration on "cold starts". This means that you don't need to run `php artisan config:cache` before deploying.

<Callout type="warning">
    You could improve the cold start time by pre-generating the config cache before deploying:

    ```bash
    php artisan config:clear && php artisan config:cache
    ```

    However Laravel will **hardcode** absolute paths and environment variables in the cached configuration. To deploy a valid cached configuration, you would need to run the commands above in Docker with the application mounted in `/var/task` (the same path as on AWS Lambda), with production environment variables available.

    For most applications we do not recommend this approach. Instead, let Bref cache the config in AWS Lambda on cold starts.
</Callout>

## Troubleshooting

In case your application is showing a blank page after being deployed, [have a look at the logs](../environment/logs.md).

## Logs

Thanks to the Bref integration, Laravel will automatically log to CloudWatch via `stderr`. You don't have to do anything.

You can learn more about logs in the [Logs guide](../environment/logs.md).

It is recommended you enable Bref's logs formatter optimized for CloudWatch:

```yaml filename="serverless.yml"
provider:
    environment:
        LOG_STDERR_FORMATTER: Bref\Monolog\CloudWatchFormatter
```

<Callout>
    This formatter will be enabled by default in Bref v3.
</Callout>

With this formatter, logs will contain structured data that can be filtered in CloudWatch Logs Insights. For example, you can filter by log level, exception class, or anything in the [Laravel Context](https://laravel.com/docs/12.x/context).

## Website assets

Have a look at the [Website guide](../use-cases/websites.mdx) to learn how to deploy a website with assets.

## Laravel Artisan

As you may have noticed, we define a function named "artisan" in `serverless.yml`. That function is using the [Console runtime](../runtimes/console.mdx), which lets us run Laravel Artisan on AWS Lambda.

For example, to execute an `artisan` command on Lambda, run the command below:

<Tabs items={['Serverless CLI', 'Bref Cloud']}>
    <Tab>
        ```bash
        serverless bref:cli --args="{artisan command and options}"
        ```

        For example:

        ```bash
        serverless bref:cli --args="route:list"
        ```
    </Tab>
    <Tab>
        ```bash
        bref command "{artisan command and options}"
        ```

        For example:

        ```bash
        bref command "route:list --help"
        ```
    </Tab>
</Tabs>

For more details follow [the "Console" guide](../runtimes/console.mdx).

### Laravel Tinker

If you are using [Bref Cloud](/cloud), you can start an interactive Tinker shell on AWS Lambda from your machine by running:

```bash
bref tinker
```

The usual flags work, for example to run Tinker in the production environment:

```bash
bref tinker --env=production
```

![](./tinker.png)

<Callout>
    Make sure to update the `bref/laravel-bridge` package to version 2.7 or higher to use this feature.
</Callout>

If you are not using Bref Cloud, you can check out this community package: [sls-tinker](https://github.com/datpmwork/sls-tinker).

## Inertia

Laravel with Inertia runs without issue, like any other website. Follow the [Websites guide](../use-cases/websites.mdx) to learn how to deploy a Laravel with assets with Bref.
